R Markdown consists of an amazing ecosystem of R packages to produce many types of technical content. Its signature capability is that is can print formatted text, run R code, and display the results, all inside a single document. Furthermore, you can easily export this document in a large variety of formats, including HTML, PDF, Word, RTF, etc. The webpage you are looking at now was written completely in RMarkdown.
At the most basic level, instead of using comments interleaved with your code in an R script (# This is a comment) you can insert nicely (formatted) text around your code in an R Markdown file. You can structure your document with headings and subheadings. You can add tables of contents. You can even generate formatted bibliographies. And the R code you insert in the document runs inside the document and the results go to the document itself, not to the console or (in the case of plots) to the Plots pane in RStudio.
This makes RMarkdown a great computer lab notebook, since you can explain what your doing and why (to colleagues or your future self). It’s also an example of reproducible research since you share not just a Word file, say, with example code, but an active document in which the code actually runs and the results are reproduced.
To understand R Markdown, we need to learn about three new things:
Markdown, a very lightweight text formatting language.
Code chunks, which allow us to incorporate R code that can be executed and whose results we can display in text, figures, and tables.
The YAML header, which encodes metadata about the output, such as the desired output format and specific formatting features.
We’ll focus on HTML output, but will also glance at the many possibilities for the output format: with R Markdown, it is possible to create not just technical reports, but also slide decks, websites, books, scientific articles, dissertations, and so on.
At the core of the R Markdown ecosystem is the rmarkdown package. We need to install this but don’t need to load it:
install.packages("rmarkdown")
Inside your directory for Code Club, create a folder for this week:
dir.create('S02E03')
Select this folder in the Files pane. Then make this your working directory:
Before we go into details, let’s first see a quick demonstration of what we’re talking about. RStudio let’s you create an example RMarkdown template with a couple of clicks.
Go to File => New File => R Markdown, change the Title to “Markdown demo”, and click OK.
Take a look at the R Markdown document, and notice that there seems to be some sort of header bounded by three dashes (=> YAML), followed by R code wrapped in strange constructs with backticks and curly brackets (=> Code chunks), and formatted written text (=> Markdown).
Before we can create output, we need to save the document. Click the Save button and save the files as demo.Rmd inside your newly created directory.
Now click the Knit button in one of the top bars, and a document should show up in a pop-up or the Viewer pane. This is the rendered output from the R Markdown document.
Notice that the YAML header is not printed (at least not verbatim) while some of the code is printed (some is hidden), and we also see code output, including a plot!
This is what the raw and rendered output look side-by-side:
We’ll now talk about Markdown, code chunks, and the YAML header in turn.
To fully appreciate the magic of Markdown and where it came from, it’s useful to just briefly visit the notion of a Markup Language.
The original markup was a blue pencil
Markdown is a very lightweight language to format plain text files, which evolved from simple in-line formatting applied in emails before those started using HTML.
Need to emphasize a word without being able to make it italic or bold? How about adding emphasis with asterisks *like so*?
| Syntax | Result |
|---|---|
| # My Title | Header level 1 (largest) |
| ## My Section | Header level 2 |
| ### My Subsection | Header level 3 – and so forth |
| *italic* or _italic_ | italic |
| **bold** or __bold__ | bold |
[Markdown Guide](markdownguide.org) |
Markdown Guide (Link with custom text) |
|  | Figure |
| - List item | Unordered (bulleted) list |
| 1. List item | Ordered (numbered) list |
`inline code` |
inline code |
``` …code… ``` |
Generic code block (for formatting only) (Alternative syntax: 4 leading spaces.) |
```r …code… ``` |
r code block (for formatting only) |
--- |
Horizontal rule (line) |
To see this formatting in action, see below an example of a raw Markdown file on the left, and its rendered (formatted) output on the right: